Tomes

A Tome is an Eldritch package that can be run on one or more Beacons. By default, Tavern includes several core Tomes to get you started. Please take a few minutes to read through the options available to you now, and be sure to refer to them as reference when creating your own Tomes. If you’re looking for information on how to run Tomes and aren’t quite ready to write your own, check out our Getting Started guide. Otherwise, adventure onwards, but with a word of warning. Eldritch provides a useful abstraction for many offensive operations, however it is under heavy active development at this time and is subject to change. After the release of Realm version 1.0.0, Eldritch will follow Semantic Versioning, to prevent Tomes from failing when breaking changes are introduced. Until then however, the Eldritch API may change. This rapid iteration will enable the language to more quickly reach maturity and ensure we provide the best possible design for operators, so thank you for your patience.

Anatomy of a Tome

A Tome has a well-defined structure consisting of three key components:

  1. metadata.yml: This file serves as the Tome’s blueprint, containing essential information in YAML format. More information about this file can be found below in the Tome Metadata section.

  2. main.eldritch: This file is where the magic happens. It contains the Eldritch code evaluated by the Tome. Testing your code with Golem before running it in production is highly recommended, since it enables signficantly faster developer velocity.

  3. assets/ (optional): Tomes have the capability to leverage additional resources stored externally. These assets, which may include data files, configuration settings, or other tools, are fetched using the implant’s callback protocol (e.g. gRPC) using the Eldritch Assets API. More information about these files can be found below in the Tome Assets section.

Tome Metadata

The metadata.yml file specifies key information about a Tome:

Name Description Required
name Display name of your Tome. Yes
description Provide a helpful description of functionality, for user’s of your Tome. Yes
author Your name/handle, so you can get credit for your amazing work! Yes
tactic The relevant MITRE ATT&CK tactic that best describes this Tome. Possible values include: UNSPECIFIED, RECON, RESOURCE_DEVELOPMENT, INITIAL_ACCESS, EXECUTION, PERSISTENCE, PRIVILEGE_ESCALATION, DEFENSE_EVASION, CREDENTIAL_ACCESS, DISCOVERY, LATERAL_MOVEMENT, COLLECTION,COMMAND_AND_CONTROL,EXFILTRATION, IMPACT. Yes
paramdefs A list of parameters that users may provide to your Tome when it is run. No

Tome Parameters

Parameters are defined as a YAML list, but have their own additional properties:

Name Description Required
name Identifier used to access the parameter via the input_params global. Yes
label Display name of the parameter for users of the Tome. Yes
type Type of the parameter in Eldritch. Current values include: string. Yes
placeholder An example value displayed to users to help explain the parameter’s purpose. Yes

Tome Parameter Example

paramdefs:
  - name: path
    type: string
    label: File path
    placeholder: "/etc/open*"

Referencing Tome Parameters

If you’ve defined a parameter for your Tome, there’s a good chance you’ll want to use it. Luckily, Eldritch makes this easy for you by providing a global input_params dictionary, which is populated with the parameter values provided to your Tome. To access a parameter, simply use the paramdef name (defined in metadata.yml). For example:

def print_path_param():
  path = input_params["path"]
  print(path)

In the above example, our metadata.yml file would specify a value for paramdefs with name: path set. Then when accessing input_params["path"] the string value provided to the Tome is returned.

Tome Metadata Example

name: List files
description: List the files and directories found at the path. Supports basic glob functionality. Does not glob more than one level.
author: hulto
tactic: RECON
paramdefs:
  - name: path
    type: string
    label: File path
    placeholder: "/etc/open*"

For more examples, please see Tavern’s first party supported Tomes.

Tome Assets

Assets are files that can be made available to your Tome if required. These assets are lazy-loaded by Agents, so if they are unused they will not increase the on-the-wire size of the payload sent to an Agent. This means it’s encouraged to include multiple versions of files, for example myimplant-linux and myimplant.exe. This enables Tomes to be cross-platform, reducing the need for redundant Tomes.

Referencing Tome Assets

When using the Eldritch Assets API, these assets are referenced based on the name of the directory your main.eldritch file is in (which may be the same as your Tome’s name). For example, with an asset imix.exe located in /mytome/assets/imix.exe (and where my metadata.yml might specify a name of “My Tome”), the correct identifier to reference this asset is mytome/assets/imix.exe (no leading /). On all platforms (even on Windows systems), use / as the path separator when referencing these assets.

Below is the directory structure used in this example:

mytome/
      /main.eldritch
      /metadata.yml
      /assets/
             /imix.exe
             /imix-linux

Importing Tomes from Git

Create Git Repository

First, create a git repository and commit your Tomes there. Realm primarily supports using GitHub private repositories (or public if suitable), but you may use any git hosting service at your own risk. If you forget to include main.eldritch or metadata.yml files, your Tomes will not be imported. Be sure to include a main.eldritch and metadata.yml in your Tome’s root directory.

Additionally, copy the URL to the repository, which you will need in the next step. For private repositories, only SSH is supported.

Git Repo Copy

Import Tome Repository

Next, navigate to the “Tomes” page and select “Import tome repository”

Tavern Tomes Page

Then, enter the repository URL copied from the previous step and click “Save Link”.

Import Tomes

Git Repository Keys

For private repositories, Tavern will need permission to clone the repository. To enable this, copy the provided SSH public key and add it to your repository. For public repositories, you may skip this step.

Import Tomes Pubkey

On GitHub, you can easily accomplish this by adding Tavern’s public key for the repository to the “Deploy Keys” setting of your repository.

GitHub Deploy Keys

Import Tomes

Now, all that’s left is to click “Import tomes”. If all goes well, your Tomes will be added to Tavern and will be displayed on the view. If Tomes are missing, be sure each Tome has a valid metadata.yml and main.eldritch file in the Tome root directory.

Anytime you need to re-import your Tomes (for example, after an update), you may navigate to the “Tomes” page and click “Refetch tomes”.